In this tutorial we show how one can manage VSL (Visual Shading Language) material objects using JavaScript. Basic understanding of VSL is assumed.

VSL Material and other VSL specific objects are defined in the r3code library. Correspondingly, the header files for them can be found from 'scripts/js/real/code' folder.

To create a VSL material:

    include("real/code/r3vsl.js");

    mat = new r3Vsl(0);
    mat.SetName("my material");

The above creates an empty VSL material object named 'my material'.

In order to let a VSL material define surface properties, you need to create and insert a so called surface shader object into the VSL material.

    include("real/code/r3mpphas.js");   // shader 

    shader = new r3Mpphaselevel(0);
    shader.SetPhase(R3CLID_PHASESURFACE);
    vsl.INSERTPROP(0, 0, shader);

The above code creates a 'phase level' VSL object and sets its type to R3CLID_PHASESURFACE. VSL objects inside this level will be able to access and define various surface properties, such as surface color.

Let's create a texture mapping object to define the surface color property:

    include("real/code/r3mptext.js");   // texture map

    texture = new r3Mptexture(0);
    texture.SetParent(shader);
    texture.SetImageName("textures/lake.jpg");

By calling the SetParent() method you link the texture object to the shader object. The SetImageName() method asks the texture mapping object to use the "textures/lake.jpg" image.

To insert the material into the current project, you need to fetch the JavaScript class managing material objects in the current project.

    matLayer = GetJS("CurrentProject.Materials");

Then you can insert the material into the current project by calling:

    matLayer.LOCKEXCLUSIVE();
    matLayer.INSERT(0, 0, vsl);
    matLayer.RELEASE();

Reflection Mapping

The technique where an image is used for defining the surface color is called texture mapping. In Realsoft 3D, images can be used for defining any material property, such as Brilliancy, Transparency, Refraction Factor, Specularity, just to name a few.

The reason why the previous example resulted in texture mapping rather than some other type of mapping is that the default output channel for the texture mapping object is 'Color'.

There are many other channels available. Each channel is identified by two properties: class and name. For example, renderer uses the channel object whose class is R3CLID_COLORCHANNEL and name is 'Color' to represent surface color.

So, to get 'reflection mapping' rather than 'color mapping', we just need to assign the texture mapping object to the 'Reflection' channel:

    texture.SetOutputChannel(R3CLID_REFLECTIONCHANNEL);
    texture.SetOutputName("Reflection");

This will turn the texture mapping into reflection mapping.

Creating VSL Curve Objects

The VSL Curve object (r3Mpcurve) is defined in the 'scripts/js/real/code/r3mpcurv.js' file. However, what makes it interesting is that it does not define any curves itself. Instead, it uses the r3Curve object for this. So, in order to create a curve object we need to know how to fetch the actual curve object and how to access the curve data in it.

Let's create a material with a curve object:

    include("real/code/r3mpcurv.js");

    // create a VSL material
    vsl = new r3Vsl(0);
    vsl.SetName("curve");

    // create a surface shader object for the material
    shader = new r3Mpphaselevel(0);
    shader.SetPhase(R3CLID_PHASESURFACE);
    vsl.INSERTPROP(0, 0, shader);

    // create a VSL curve object into the shader object
    mpcurve = new r3Mpcurve(0);
    mpcurve.SetParent(shader);

    // attach to color channel
    mpcurve.SetOutputChannel(R3CLID_COLORCHANNEL);
    mpcurve.SetOutputName("Color");

So, we have now created a VSL curve object and attached it to the Surface Color channel.

In order to add some points into the curve object, we must first fetch the actual curve object from the VSL curve object. This can be done by calling the GetCurve() method.

    curve = mpcurve.GetCurve();

The above call returns r3Curve object (scripts/js/real/code/r3curve.js).

By default all curve objects have two points, defining a linear curve. Let's get rid of these default curves. To delete existing points from the curve, call:

    curve.DELETEALLPOINTS();

Then we can add a number of points to the curve by calling ADDPOINTIFNOTONLINE method. Let's add three points to the curve:

    curve.ADDPOINTIFNOTONLINE(R3TID_VECTOR, new r3Vect(0, 0, 0), new r3Vect(0.3, 0.2, 0.1));
    curve.ADDPOINTIFNOTONLINE(R3TID_VECTOR, new r3Vect(0.5, 0.5, 0.5), new r3Vect(0.4, 0.1, 0.2));
    curve.ADDPOINTIFNOTONLINE(R3TID_VECTOR, new r3Vect(1, 1, 1), new r3Vect(0.9, 0.7, 0.6));

The first vector value specifies x coordinates for the point to be added. The second vector parameter specifies corresponding y values.

Because we attached the curve object to Color channel, the curve defines three sub curves: one for each color sub channel (red, green, blue). Therefore, we must pass vectors to the ADDPOINTIFNOTONLINE method. If we attached the curve object to say the Alpha channel, there would be only one curve. Correspondingly, we would call:

    curve.ADDPOINTIFNOTONLINE(R3TID_FLOAT, 0.1, 0.5);

The final step is to insert the VSL material into the current project:

    matLayer.LOCKEXCLUSIVE();
    matLayer.INSERT(0, 0, vsl);
    matLayer.RELEASE();